home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3c / dbm.z / dbm
Encoding:
Text File  |  2001-04-17  |  8.7 KB  |  199 lines
  1.  
  2.  
  3.  
  4. DDDDBBBBMMMM((((3333BBBB))))                                                                DDDDBBBBMMMM((((3333BBBB))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      dbm: dbminit, dbminit64, dbmclose, dbmclose64, fetch, fetch64, store,
  10.      store64, delete, delete64, firstkey, firstkey64, nextkey, nextkey64 -
  11.      data base subroutines
  12.  
  13. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  14.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddbbbbmmmm....hhhh>>>>
  15.  
  16.      ttttyyyyppppeeeeddddeeeeffff ssssttttrrrruuuucccctttt {{{{
  17.           cccchhhhaaaarrrr ****ddddppppttttrrrr;;;;
  18.           iiiinnnntttt ddddssssiiiizzzzeeee;;;;
  19.      }}}} ddddaaaattttuuuummmm;;;;
  20.  
  21.      iiiinnnntttt ddddbbbbmmmmiiiinnnniiiitttt((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ffffiiiilllleeee))));;;;
  22.  
  23.      iiiinnnntttt ddddbbbbmmmmiiiinnnniiiitttt66664444((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ffffiiiilllleeee))));;;;
  24.  
  25.      vvvvooooiiiidddd ddddbbbbmmmmcccclllloooosssseeee((((vvvvooooiiiidddd))));;;;
  26.  
  27.      vvvvooooiiiidddd ddddbbbbmmmmcccclllloooosssseeee66664444((((vvvvooooiiiidddd))));;;;
  28.  
  29.      ddddaaaattttuuuummmm ffffeeeettttcccchhhh((((ddddaaaattttuuuummmm kkkkeeeeyyyy))));;;;
  30.  
  31.      ddddaaaattttuuuummmm ffffeeeettttcccchhhh66664444((((ddddaaaattttuuuummmm kkkkeeeeyyyy))));;;;
  32.  
  33.      iiiinnnntttt ssssttttoooorrrreeee((((ddddaaaattttuuuummmm kkkkeeeeyyyy,,,, ddddaaaattttuuuummmm ccccoooonnnntttteeeennnntttt))));;;;
  34.  
  35.      iiiinnnntttt ssssttttoooorrrreeee66664444((((ddddaaaattttuuuummmm kkkkeeeeyyyy,,,, ddddaaaattttuuuummmm ccccoooonnnntttteeeennnntttt))));;;;
  36.  
  37.      iiiinnnntttt ddddeeeelllleeeetttteeee((((ddddaaaattttuuuummmm kkkkeeeeyyyy))));;;;
  38.  
  39.      iiiinnnntttt ddddeeeelllleeeetttteeee66664444((((ddddaaaattttuuuummmm kkkkeeeeyyyy))));;;;
  40.  
  41.      ddddaaaattttuuuummmm ffffiiiirrrrssssttttkkkkeeeeyyyy((((vvvvooooiiiidddd))));;;;
  42.  
  43.      ddddaaaattttuuuummmm ffffiiiirrrrssssttttkkkkeeeeyyyy66664444((((vvvvooooiiiidddd))));;;;
  44.  
  45.      ddddaaaattttuuuummmm nnnneeeexxxxttttkkkkeeeeyyyy((((ddddaaaattttuuuummmm kkkkeeeeyyyy))));;;;
  46.  
  47.      ddddaaaattttuuuummmm nnnneeeexxxxttttkkkkeeeeyyyy66664444((((ddddaaaattttuuuummmm kkkkeeeeyyyy))));;;;
  48.  
  49. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  50.      NNNNooootttteeee:::: tttthhhheeee ddddbbbbmmmm lllliiiibbbbrrrraaaarrrryyyy hhhhaaaassss bbbbeeeeeeeennnn ssssuuuuppppeeeerrrrsssseeeeddddeeeedddd bbbbyyyy nnnnddddbbbbmmmm((((3333BBBB)))),,,, aaaannnndddd iiiissss nnnnoooowwww
  51.      iiiimmmmpppplllleeeemmmmeeeennnntttteeeedddd uuuussssiiiinnnngggg nnnnddddbbbbmmmm....  These functions maintain key/content pairs in a
  52.      data base.  The ddddbbbbmmmm functions will handle very large (a billion blocks)
  53.      databases and will access a keyed item in one or two file system
  54.      accesses.  The ddddbbbbmmmm66664444 routines are identical to their ddddbbbbmmmm counterparts
  55.      except that they can be used to operate on data bases larger than 2
  56.      Gigabytes.
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. DDDDBBBBMMMM((((3333BBBB))))                                                                DDDDBBBBMMMM((((3333BBBB))))
  71.  
  72.  
  73.  
  74.      _K_e_ys and _c_o_n_t_e_n_ts are described by the _d_a_t_u_m typedef.  A _d_a_t_u_m specifies
  75.      a string of _d_s_i_z_e bytes pointed to by _d_p_t_r. Arbitrary binary data, as
  76.      well as normal ASCII strings, are allowed.  The data base is stored in
  77.      two files.  One file is a directory containing a bit map and has `.dir'
  78.      as its suffix.  The second file contains all data and has `.pag' as its
  79.      suffix.
  80.  
  81.      Before a database can be accessed, it must be opened by _d_b_m_i_n_i_t.  At the
  82.      time of this call, the files _f_i_l_e....ddddiiiirrrr and _f_i_l_e....ppppaaaagggg must exist.  (An empty
  83.      database is created by creating zero-length `.dir' and `.pag' files.)
  84.  
  85.      Once open, the data stored under a key is accessed by _f_e_t_c_h and data is
  86.      placed under a key by _s_t_o_r_e.  A key (and its associated contents) is
  87.      deleted by _d_e_l_e_t_e.  A linear pass through all keys in a database may be
  88.      made, in an (apparently) random order, by use of _f_i_r_s_t_k_e_y and _n_e_x_t_k_e_y.
  89.      _F_i_r_s_t_k_e_y will return the first key in the database.  With any key _n_e_x_t_k_e_y
  90.      will return the next key in the database.  The following code will
  91.      traverse the data base:
  92.  
  93.           for (key = firstkey(); key.dptr != NULL; key = nextkey(key))
  94.  
  95.  
  96. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  97.      All functions that return an _i_n_t indicate errors with negative values.  A
  98.      zero return indicates ok.  Routines that return a _d_a_t_u_m indicate errors
  99.      with a null (0) _d_p_t_r.
  100.  
  101.      Some error conditions will set _e_r_r_n_o. These are:  EEEENNNNOOOOMMMMEEEEMMMM:::: runtime memory
  102.      allocation failed; EEEEPPPPEEEERRRRMMMM:::: file permissions don't match the process
  103.      euid/egid permissions; EEEEIIIINNNNVVVVAAAALLLL:::: key+data sizes for _d_b_m__s_t_o_r_e exceed the
  104.      internal block size; EEEEFFFFBBBBIIIIGGGG:::: hash table overflow would cause the maximum
  105.      dbm file size to be exceeded.
  106.  
  107.  
  108. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  109.      ndbm(3B) and Berkeley db: dbopen(3)
  110.  
  111. BBBBUUUUGGGGSSSS
  112.      _D_p_t_r pointers returned by these subroutines point into static storage
  113.      that is changed by subsequent calls.
  114.  
  115.      _d_b_m databases may not be portable across machines with different
  116.      alignment restrictions or different byte sexes.
  117.  
  118.      _D_p_t_r pointers returned by these subroutines point into possibly non word
  119.      aligned storage. You cannot assume that you can cast the _D_p_t_r pointer
  120.      into an arbitrary data type and dereference it.  This is a general rule
  121.      in ANSI-C rather than _d_b_m specific, but users often hit it while using
  122.      _d_b_m.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. DDDDBBBBMMMM((((3333BBBB))))                                                                DDDDBBBBMMMM((((3333BBBB))))
  137.  
  138.  
  139.  
  140.      The sum of the sizes of a key/content pair must not exceed the internal
  141.      block size minus the _d_b_m small book-keeping overhead (currently _PBLKSIZ
  142.      - 6 = 1018 bytes).  Moreover all key/content pairs that hash together
  143.      must fit on a single block.  For a dbm-like implementation with much less
  144.      size limitations, check out ddddbbbbooooppppeeeennnn((((3333)))) (Berkeley DB).
  145.  
  146.      _S_t_o_r_e will return an error in the event that a disk block fills with
  147.      inseparable data.
  148.  
  149.      _D_e_l_e_t_e does not physically reclaim file space, although it does make it
  150.      available for reuse.
  151.  
  152.      The order of keys presented by _f_i_r_s_t_k_e_y and _n_e_x_t_k_e_y depends on a hashing
  153.      function, not on anything interesting.
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.